<login-module code="..." flag="..." module="..."> <module-option name="..." value="..."/> </login-module>
The security subsystem is the subsystem that brings the security services provided by PicketBox to the WildFly 8 server instances.
If you are looking to secure the management interfaces for the management of the domain then you should read the Securing the Management Interfaces chapter as the management interfaces themselves are not run within a WildFly process so use a custom configuration.
When deploying applications to WildFly most of the time it is likely that you would be deploying a web application or EJBs and just require a security domain to be defined with login modules to verify the users identity, this chapter aims to provide additional detail regarding the architecture and capability of the security subsystem however if you are just looking to define a security domain and leave the rest to the container please jump to the security-domains section.
The security subsystem operates by using a security context associated with the current request, this security context then makes available to the relevant container a number of capabilities from the configured security domain, the capabilities exposed are an authentication manager, an authorization manager, an audit manager and a mapping manager.
The authentication manager is the component that performs the actual authentication taking the declared users identity and their credential so that the login context for the security domain can be used to 'login' the user using the configured login module or modules.
The authorization manager is a component which can be obtained by the container from the current security context to either obtain information about a users roles or to perform an authorization check against a resource for the currently authenticated user.
The audit manager from the security context is the component that can be used to log audit events in relation to the security domain.
The mapping manager can be used to assign additional principals, credentials, roles or attributes to the authenticated subject.
By default a lot of defaults have already been selected for the security subsystem and unless there is a specific implementation detail you need to change, these defaults should not require modification. This chapter describes all of the possible configuration attributes for completeness but do keep in mind that not all will need to be changed.
The security subsystem is enabled by default by the addition of the following extension: -
<extension module="org.jboss.as.security"/>
The namespace used for the configuration of the security subsystem is urn:jboss:domain:security:1.0, the configuration is defined within the <subsystem> element from this namespace.
The <subsystem> element can optionally contain the following child elements.
security-management
subject-factory
security-domains
security-properties
This element is used to override some of the high level implementation details of the PicketBox implementation if you have a need to change some of this behaviour.
The element can have any or the following attributes set, all of which are optional.
|
authentication-manager-class-name |
Specifies the AuthenticationManager implementation class name to use. |
|
deep-copy-subject-mode |
Sets the copy mode of subjects done by the security managers to be deep copies that makes copies of the subject principals and credentials if they are cloneable. It should be set to true if subject include mutable content that can be corrupted when multiple threads have the same identity and cache flushes/logout clearing the subject in one thread results in subject references affecting other threads. Default value is "false". |
|
default-callback-handler-class-name |
Specifies a global class name for the CallbackHandler implementation to be used with login modules. |
|
authorization-manager-class-name |
Attribute specifies the AuthorizationManager implementation class name to use. |
|
audit-manager-class-name |
Specifies the AuditManager implementation class name to use. |
|
identity-trust-manager-class-name |
Specifies the IdentityTrustManager implementation class name to use. |
|
mapping-manager-class-name |
Specifies the MappingManager implementation class name to use. |
The subject factory is responsible for creating subject instances, this also makes use of the authentication manager to actually verify the caller. It is used mainly by JCA components to establish a subject. It is not likely this would need to be overridden but if it is required the "subject-factory-class-name" attribute can be specified on the subject-factory element.
This portion of the configuration is where the bulk of the security subsystem configuration will actually take place for most administrators, the security domains contain the configuration which is specific to a deployment.
The security-domains element can contain numerous <security-domain> definitions, a security-domain can have the following attributes set:
|
name |
The unique name of this security domain. |
|
extends |
The optional name of a security domain extended by this security domain. |
|
cache-type |
The type of authentication cache to use with this domain. If this attribute is removed no cache will be used. Allowed values are "default" or "infinispan" |
The following elements can then be set within the security-domain to configure the domain behaviour.
The authentication element is used to hold the list of login modules that will be used for authentication when this domain is used, the structure of the login-module element is:
<login-module code="..." flag="..." module="..."> <module-option name="..." value="..."/> </login-module>
The code attribute is used to specify the implementing class of the login module which can either be the full class name or one of the abbreviated names from the following list:
|
Code |
Classname |
|
Client |
org.jboss.security.ClientLoginModule |
|
Certificate |
org.jboss.security.auth.spi.BaseCertLoginModule |
|
CertificateUsers |
org.jboss.security.auth.spi.BaseCertLoginModule |
|
CertificateRoles |
org.jboss.security.auth.spi.CertRolesLoginModule |
|
Database |
org.jboss.security.auth.spi.DatabaseServerLoginModule |
|
DatabaseCertificate |
org.jboss.security.auth.spi.DatabaseCertLoginModule |
|
DatabaseUsers |
org.jboss.security.auth.spi.DatabaseServerLoginModule |
|
Identity |
org.jboss.security.auth.spi.IdentityLoginModule |
|
Ldap |
org.jboss.security.auth.spi.LdapLoginModule |
|
LdapExtended |
org.jboss.security.auth.spi.LdapExtLoginModule |
|
RoleMapping |
org.jboss.security.auth.spi.RoleMappingLoginModule |
|
RunAs |
org.jboss.security.auth.spi.RunAsLoginModule |
|
Simple |
org.jboss.security.auth.spi.SimpleServerLoginModule |
|
ConfiguredIdentity |
org.picketbox.datasource.security.ConfiguredIdentityLoginModule |
|
SecureIdentity |
org.picketbox.datasource.security.SecureIdentityLoginModule |
|
PropertiesUsers |
org.jboss.security.auth.spi.PropertiesUsersLoginModule |
|
SimpleUsers |
org.jboss.security.auth.spi.SimpleUsersLoginModule |
|
LdapUsers |
org.jboss.security.auth.spi.LdapUsersLoginModule |
|
Kerberos |
com.sun.security.auth.module.Krb5LoginModule |
|
SPNEGOUsers |
org.jboss.security.negotiation.spnego.SPNEGOLoginModule |
|
AdvancedLdap |
org.jboss.security.negotiation.AdvancedLdapLoginModule |
|
AdvancedADLdap |
org.jboss.security.negotiation.AdvancedADLoginModule |
|
UsersRoles |
org.jboss.security.auth.spi.UsersRolesLoginModule |
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded. Specifying it is not necessary if one of the abbreviated names in the above list is used.
The flag attribute is used to specify the JAAS flag for this module and should be one of required, requisite, sufficient, or optional.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
See Authentication Modules for further details on the various modules listed above.
The authentication-jaspi is used to configure a Java Authentication SPI (JASPI) provider as the authentication mechanism. A security domain can have either a <authentication> or a <authentication-jaspi> element, but not both. We set up JASPI by configuring one or more login modules inside the login-module-stack element and setting up an authentication module. Here is the structure of the authentication-jaspi element:
<login-module-stack name="...">
<login-module code="..." flag="..." module="...">
<module-option name="..." value="..."/>
</login-module>
</login-module-stack>
<auth-module code="..." login-module-stack-ref="...">
<module-option name="..." value="..."/>
</auth-module>
The login-module-stack-ref attribute value must be the name of the login-module-stack element to be used. The sub-element login-module is configured just like in the authentication part
Authorization in the AS container is normally done with RBAC (role based access control) but there are situations where a more fine grained authorization policy is required. The authorization element allows definition of different authorization modules to used, such that authorization can be checked with JACC (Java Authorization Contract for Containers) or XACML (eXtensible Access Control Markup Language). The structure of the authorization element is:
<policy-module code="..." flag="..." module="..."> <module-option name="..." value="..."/> </policy-module>
The code attribute is used to specify the implementing class of the policy module which can either be the full class name or one of the abbreviated names from the following list:
|
Code |
Classname |
|
DenyAll |
org.jboss.security.authorization.modules.AllDenyAuthorizationModule |
|
PermitAll |
org.jboss.security.authorization.modules.AllPermitAuthorizationModule |
|
Delegating |
org.jboss.security.authorization.modules.DelegatingAuthorizationModule |
|
Web |
org.jboss.security.authorization.modules.WebAuthorizationModule |
|
JACC |
org.jboss.security.authorization.modules.JACCAuthorizationModule |
|
XACML |
org.jboss.security.authorization.modules.XACMLAuthorizationModule |
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded. Specifying it is not necessary if one of the abbreviated names in the above list is used.
The flag attribute is used to specify the JAAS flag for this module and should be one of required, requisite, sufficient, or optional.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
The mapping element defines additional mapping of principals, credentials, roles and attributes for the subject. The structure of the mapping element is:
<mapping-module type="..."code="..." module="..."> <module-option name="..." value="..."/> </mapping-module>
The type attribute reflects the type of mapping of the provider and should be one of principal, credential, role or attribute. By default "role" is the type used if the attribute is not set.
The code attribute is used to specify the implementing class of the login module which can either be the full class name or one of the abbreviated names from the following list:
|
Code |
Classname |
|
PropertiesRoles |
org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider |
|
SimpleRoles |
org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider |
|
DeploymentRoles |
org.jboss.security.mapping.providers.DeploymentRolesMappingProvider |
|
DatabaseRoles |
org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider |
|
LdapRoles |
org.jboss.security.mapping.providers.role.LdapRolesMappingProvider |
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded. Specifying it is not necessary if one of the abbreviated names in the above list is used.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
The audit element can be used to define a custom audit provider. The default implementation used is org.jboss.security.audit.providers.LogAuditProvider. The structure of the audit element is:
<provider-module code="..." module="..."> <module-option name="..." value="..."/> </provider-module>
The code attribute is used to specify the implementing class of the provider module.
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
The jsse element defines configuration for keystores and truststores that can be used for SSL context configuration or for certificate storing/retrieving.
The set of attributes (all of them optional) of this element are:
|
keystore-password |
Password of the keystore |
|
keystore-type |
Type of the keystore. By default it's "JKS" |
|
keystore-url |
URL where the keystore file can be found |
|
keystore-provider |
Provider of the keystore. The default JDK provider for the keystore type is used if this attribute is null |
|
keystore-provider-argument |
String that can be passed as the argument of the keystore Provider constructor |
|
key-manager-factory-algorithm |
Algorithm of the KeyManagerFactory. The default JDK algorithm of the key manager factory is used if this attribute is null |
|
key-manager-factory-provider |
Provider of the KeyManagerFactory. The default JDK provider for the key manager factory algorithm is used if this attribute is null |
|
truststore-password |
Password of the truststore |
|
truststore-type |
Type of the truststore. By deafult it's "JKS" |
|
truststore-url |
URL where the truststore file can be found |
|
truststore-provider |
Provider of the truststore. The default JDK provider for the truststore type is used if this attribute is null |
|
truststore-provider-argument |
String that can be passed as the argument of the truststore Provider constructor |
|
trust-manager-factory-algorithm |
Algorithm of the TrustManagerFactory. The default JDK algorithm of the trust manager factory is used if this attribute is null |
|
trust-manager-factory-provider |
Provider of the TrustManagerFactory. The default JDK provider for the trust manager factory algorithm is used if this attribute is null |
|
client-alias |
Alias of the keystore to be used when creating client side SSL sockets |
|
server-alias |
Alias of the keystore to be used when creating server side SSL sockets |
|
service-auth-token |
Validation token to enable third party services to retrieve a keystore Key. This is typically used to retrieve a private key for signing purposes |
|
client-auth |
Flag to indicate if the server side SSL socket should require client authentication. Default is "false" |
|
cipher-suites |
Comma separated list of cipher suites to be used by a SSLContext |
|
protocols |
Comma separated list of SSL protocols to be used by a SSLContext |
The optional additional-properties element can be used to include other options. The structure of the jsse element is:
<jsse keystore-url="..." keystore-password="..." keystore-type="..." keystore-provider="..." keystore-provider-argument="..." key-manager-factory-algorithm="..." key-manager-factory-provider="..." truststore-url="..." truststore-password="..." truststore-type="..." truststore-provider="..." truststore-provider-argument="..." trust-manager-factory-algorithm="..." trust-manager-factory-provider="..." client-alias="..." server-alias="..." service-auth-token="..." client-auth="..." cipher-suites="..." protocols="...">
<additional-properties>x=y
a=b
</additional-properties>
</jsse>
This element is used to specify additional properties as required by the security subsystem, properties are specified in the following format:
<security-properties> <property name="..." value="..."/> </security-properties>
The property element can be repeated as required for as many properties need to be defined.
Each property specified is set on the java.security.Security class.